* be controlling each of these virtual devices. Physical devices may also
* be "floating", which means they are not attached to any virtual device.
*
- * ## Master and slave devices
+ * # Master and slave devices
*
* |[
* carlos@sacarino:~$ xinput list
* linkend="monitoring-changes">Monitoring changes</link> for additional
* details.
*
- * ## Manipulating accelerators
+ * # Manipulating accelerators
*
* New accelerators can be added using gtk_accel_map_add_entry().
* To search for specific accelerator, use gtk_accel_map_lookup_entry().
* locked using gtk_accel_map_lock_path(). Unlocking is done using
* gtk_accel_map_unlock_path().
*
- * ## Saving and loading accelerator maps
+ * # Saving and loading accelerator maps
*
* Accelerator maps can be saved to and loaded from some external
* resource. For simple saving and loading from file,
* Saving and loading can also be done by providing file descriptor
* to gtk_accel_map_save_fd() and gtk_accel_map_load_fd().
*
- * ## Monitoring changes
+ * # Monitoring changes
*
* #GtkAccelMap object is only useful for monitoring changes of
* accelerators. By connecting to #GtkAccelMap::changed signal, one
* handling buttons, you can use the #GTK_ASSISTANT_PAGE_CUSTOM page
* type and handle buttons yourself.
*
- * ## GtkAssistant as GtkBuildable
+ * # GtkAssistant as GtkBuildable
*
* The GtkAssistant implementation of the #GtkBuildable interface
* exposes the @action_area as internal children with the name
* with high key binding configurability which requires no application
* or toolkit side changes.
*
- * ## Installing a key binding
+ * # Installing a key binding
*
* A CSS file binding consists of a 'binding-set' definition and a match
* statement to apply the binding set to specific widget types. Details
* of a #GtkEntry widget to the #GtkEntry::move-cursor signal (so
* movement occurs in 3-character steps), the following binding can be
* used:
+ *
* |[
* @binding-set MoveCursor3
* {
* }
* ]|
*
- * ## Unbinding existing key bindings
+ * # Unbinding existing key bindings
*
* GTK+ already defines a number of useful bindings for the widgets
* it provides. Because custom bindings set up in CSS files take
* <link linkend="gtk-bindings-install">Installing a key binding</link>
* works as expected. The same mechanism can not be used to "unbind"
* existing bindings, however.
+ *
* |[
* @binding-set MoveCursor3
* {
* gtk-key-bindings: MoveCursor3;
* }
* ]|
+ *
* The above example will not have the desired effect of causing
* "<Control>Right" and "<Control>Left" key presses to
* be ignored by GTK+. Instead, it just causes any existing bindings
* will eventually lookup and find the default GTK+ bindings for
* entries which implement word movement. To keep GTK+ from activating
* its default bindings, the "unbind" keyword can be used like this:
+ *
* |[
* @binding-set MoveCursor3
* {
* gtk-key-bindings: MoveCursor3;
* }
* ]|
+ *
* Now, GTK+ will find a match when looking up "<Control>Right"
* and "<Control>Left" key presses before it resorts to its default
* bindings, and the match instructs it to abort ("unbind") the search,
* The function gtk_builder_connect_signals() and variants thereof can be
* used to connect handlers to the named signals in the description.
*
- * ## GtkBuilder UI Definitions
+ * # GtkBuilder UI Definitions
*
* GtkBuilder parses textual descriptions of user interfaces which are
* specified in an XML format which can be roughly described by the
* are more limited in scope. It is common to use `.ui`
* as the filename extension for files containing GtkBuilder UI
* definitions.
+ *
* |[
* <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gtk/gtkbuilder.rnc">
* <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
* </xi:include>
* ]|
+ *
* The toplevel element is <interface>. It optionally takes a
* "domain" attribute, which will make the builder look for translated
* strings using dgettext() in the domain specified. This can also be
* The possible values for the "type" attribute are described in the
* sections describing the widget-specific portions of UI definitions.
*
- * ## A GtkBuilder UI Definition
+ * # A GtkBuilder UI Definition
*
* |[
* <interface>
* Usually users dont have to interact with the #GtkCellArea directly
* unless they are implementing a cell-layouting widget themselves.
*
- * ## Requesting area sizes
- *
+ * # Requesting area sizes
+ *
* As outlined in <link linkend="geometry-management">GtkWidget's
* geometry management section</link>, GTK+ uses a height-for-width
* geometry management system to compute the sizes of widgets and user
*
* In order to request the width of all the rows at the root level
* of a #GtkTreeModel one would do the following:
+ *
* |[<!-- language="C" -->
* GtkTreeIter iter;
* gint minimum_width;
* }
* gtk_cell_area_context_get_preferred_width (context, &minimum_width, &natural_width);
* ]|
+ *
* Note that in this example it's not important to observe the
* returned minimum and natural width of the area for each row
* unless the cell-layouting object is actually interested in the
*
* A simple example where rows are rendered from top to bottom and
* take up the full width of the layouting widget would look like:
+ *
* |[<!-- language="C" -->
* static void
* foo_get_preferred_width (GtkWidget *widget,
* gtk_cell_area_context_get_preferred_width (priv->context, minimum_size, natural_size);
* }
* ]|
+ *
* In the above example the Foo widget has to make sure that some
* row sizes have been calculated (the amount of rows that Foo judged
* was appropriate to request space for in a single timeout iteration)
*
* In order to request the height for width of all the rows at the
* root level of a #GtkTreeModel one would do the following:
+ *
* |[<!-- language="C" -->
* GtkTreeIter iter;
* gint minimum_height;
* valid = gtk_tree_model_iter_next (model, &iter);
* }
* ]|
+ *
* Note that in the above example we would need to cache the heights
* returned for each row so that we would know what sizes to render the
* areas for each row. However we would only want to really cache the
* from a scrolled window it simply continues to drive the scrollbar
* values while more and more height is required for the row heights
* that are calculated in the background.
- *
- * ## Rendering Areas
+ *
+ * # Rendering Areas
*
* Once area sizes have been aquired at least for the rows in the
* visible area of the layouting widget they can be rendered at
*
* A crude example of how to render all the rows at the root level
* runs as follows:
+ *
* |[<!-- language="C" -->
* GtkAllocation allocation;
* GdkRectangle cell_area = { 0, };
* valid = gtk_tree_model_iter_next (model, &iter);
* }
* ]|
+ *
* Note that the cached height in this example really depends on how
* the layouting widget works. The layouting widget might decide to
* give every row its minimum or natural height or, if the model content
* would make sense to calculate the allocation for each row at
* #GtkWidget::size-allocate time using gtk_distribute_natural_allocation().
*
- * ## Handling Events and Driving Keyboard Focus
+ * # Handling Events and Driving Keyboard Focus
*
* Passing events to the area is as simple as handling events on any
* normal widget and then passing them to the gtk_cell_area_event()
*
* A basic example of how the #GtkWidgetClass.focus() virtual method
* should be implemented:
+ *
* |[<!-- language="C" -->
* static gboolean
* foo_focus (GtkWidget *widget,
* return have_focus;
* }
* ]|
+ *
* Note that the layouting widget is responsible for matching the
* GtkDirectionType values to the way it lays out its cells.
*
- * ## Cell Properties
+ * # Cell Properties
*
* The #GtkCellArea introduces cell properties for #GtkCellRenderers
* in very much the same way that #GtkContainer introduces
* gtk_cell_layout_set_cell_data_func() that is called to determine the
* value of the attribute for each cell that is rendered.
*
- * ## GtkCellLayouts as GtkBuildable
+ * # GtkCellLayouts as GtkBuildable
*
* Implementations of GtkCellLayout which also implement the GtkBuildable
* interface (#GtkCellView, #GtkIconView, #GtkComboBox,
* <property> elements defined in the normal way.
*
* Here is a UI definition fragment specifying cell properties:
+ *
* |[
* <object class="GtkTreeViewColumn">
* <child>
* </object>
* ]|
*
- * ## Subclassing GtkCellLayout implementations
+ * # Subclassing GtkCellLayout implementations
*
* When subclassing a widget that implements #GtkCellLayout like
* #GtkIconView or #GtkComboBox, there are some considerations related
* to the fact that these widgets internally use a #GtkCellArea.
* The cell area is exposed as a construct-only property by these
* widgets. This means that it is possible to e.g. do
+ *
* |[<!-- language="C" -->
* combo = g_object_new (GTK_TYPE_COMBO_BOX, "cell-area", my_cell_area, NULL);
* ]|
+ *
* to use a custom cell area with a combo box. But construct properties
* are only initialized after instance init()
* functions have run, which means that using functions which rely on
* cause the default cell area to be instantiated. In this case, a provided
* construct property value will be ignored (with a warning, to alert
* you to the problem).
+ *
* |[<!-- language="C" -->
* static void
* my_combo_box_init (MyComboBox *b)
* return g_object_new (MY_TYPE_COMBO_BOX, "cell-area", area, NULL);
* }
* ]|
+ *
* If supporting alternative cell areas with your derived widget is
* not important, then this does not have to concern you. If you want
* to support alternative cell areas, you can do so by moving the
* You should not call gtk_combo_box_set_model() or attempt to pack more cells
* into this combo box via its GtkCellLayout interface.
*
- * ## GtkComboBoxText as GtkBuildable
+ * # GtkComboBoxText as GtkBuildable
*
* The GtkComboBoxText implementation of the GtkBuildable interface
* supports adding items directly using the <items> element
* children in a horizontal row, and a #GtkGrid arranges the widgets it contains
* in a two-dimensional grid.
*
- * ## Height for width geometry management
+ * # Height for width geometry management
*
* GTK+ uses a height-for-width (and width-for-height) geometry management system.
* Height-for-width means that a widget can change how much vertical space it needs,
* See <link linkend="geometry-management">GtkWidget's geometry management section</link>
* to learn more about implementing height-for-width geometry management for widgets.
*
- * ## Child properties
+ * # Child properties
*
* GtkContainer introduces child properties.
* These are object properties that are not specific
* gtk_container_child_get_valist(). To emit notification about child property
* changes, use gtk_widget_child_notify().
*
- * ## GtkContainer as GtkBuildable
+ * # GtkContainer as GtkBuildable
*
* The GtkContainer implementation of the GtkBuildable interface
* supports a <packing> element for children, which can
* (see the #GtkSettings:gtk-theme-name setting) and datadir
* is the prefix configured when GTK+ was compiled, unless overridden by the
* `GTK_DATA_PREFIX` environment variable.
- *
- * ## Style sheets
+ *
+ * # Style sheets
*
* The basic structure of the style sheets understood by this provider is
* a series of statements, which are either rule sets or '@-rules', separated
* GtkLabel widgets that are direct children of a GtkNotebook.
*
* An example of widget classes and names in selectors:
+ *
* |[
* /* Theme labels that are descendants of a window */
* GtkWindow GtkLabel {
* pseudo-classes in CSS. The available pseudo-classes for widget states
* are :active, :prelight (or :hover), :insensitive, :selected, :focused
* and :inconsistent.
- *
+ *
* And example for styling specific widget states:
* |[
* /* Theme active (pressed) buttons */
* sets are merged. As in CSS, rules apply by specificity, so the rules
* whose selectors more closely match a widget path will take precedence
* over the others.
- *
- * ## @ Rules
+ *
+ * # @ Rules
*
* GTK+'s CSS supports the @import rule, in order to load another
* CSS style sheet in addition to the currently parsed one.
* }
* ]|
*
- * ## Symbolic colors
+ * # Symbolic colors
*
* Besides being able to define color names, the CSS parser is also able
* to read different color expressions, which can also be nested, providing
* </tgroup>
* </informaltable>
*
- * ## Gradients
+ * # Gradients
*
* Linear or radial Gradients can be used as background images.
*
* color-stop (0.2, @yellow),
* color-stop (1, @green))</literallayout>
*
- * ## Text shadow
+ * # Text shadow
*
* A shadow list can be applied to text or symbolic icons, using the CSS3
* text-shadow syntax, as defined in the
* always rendered front-back, i.e. the first shadow specified is on top of the
* others. Shadows can thus overlay each other, but they can never overlay the
* text or icon itself, which is always rendered on top of the shadow layer.
- *
- * ## Box shadow
+ *
+ * # Box shadow
*
* Themes can apply shadows on framed elements using the CSS3 box-shadow syntax,
* as defined in the
* of shadow elements in the box-shadow property. Shadows are always rendered
* front-back, i.e. the first shadow specified is on top of the others, so they may
* overlap other boxes or other shadows.
- *
- * ## Border images
+ *
+ * # Border images
*
* Images and gradients can also be used in slices for the purpose of creating
* scalable borders.
* This border image was specified with
* <literallayout>url("gradient1.png") 10 10 10 10 stretch</literallayout>
*
- * ## Transitions
+ * # Transitions
*
* Styles can specify transitions that will be used to create a gradual
* change in the appearance when a widget state changes. The following
* The option after the duration determines the transition function from a
* small set of predefined functions.
*
- * ## Linear transition
+ * # Linear transition
*
* 
*
*
* 
*
- * ## Supported properties
+ * # Supported properties
*
* Properties are the part that differ the most to common CSS,
* not all properties are supported (some are planned to be
* supported eventually, some others are meaningless or don't
* map intuitively in a widget based environment).
- *
+ *
* The currently supported properties are:
* <informaltable>
* <tgroup cols="4">
* }
* ]|
*
- * ## GtkDialog as GtkBuildable
+ * # GtkDialog as GtkBuildable
*
* The GtkDialog implementation of the #GtkBuildable interface exposes the
* @vbox and @action_area as internal children with the names "vbox" and
* - The #GtkWidget::realize signal to take any necessary actions
* when the widget is instantiated on a particular display.
* (Create GDK resources in response to this signal.)
- *
+ *
* - The #GtkWidget::configure-event signal to take any necessary
* actions when the widget changes size.
*
* to add it to the expander. When the expander is toggled, it will take
* care of showing and hiding the child automatically.
*
- * ## Special Usage
+ * # Special Usage
*
* There are situations in which you may prefer to show and hide the
* expanded widget yourself, such as when you want to actually create
* }
* ]|
*
- * ## GtkExpander as GtkBuildable
+ * # GtkExpander as GtkBuildable
*
* The GtkExpander implementation of the GtkBuildable interface
* supports placing a child in the label position by specifying
* - Volumes: are provided by the underlying filesystem abstraction. They are
* the "roots" of the filesystem.
*
- * ## File Names and Encodings
+ * # File Names and Encodings
*
* When the user is finished selecting files in a
* #GtkFileChooser, your program can get the selected names
* to convert filenames into strings that can be passed to GTK+
* widgets.
*
- * ## Adding a Preview Widget
+ * # Adding a Preview Widget
*
* You can add a custom preview widget to a file chooser and then
* get notification about when the preview needs to be updated.
* }
* ]|
*
- * ## Adding Extra Widgets
+ * # Adding Extra Widgets
*
* You can add extra widgets to a file chooser to provide options
* that are not present in the default design. For example, you
* gtk_file_chooser_set_extra_widget (my_file_chooser, toggle);
* }
* ]|
- *
+ *
* If you want to set more than one extra widget in the file
* chooser, you can a container such as a #GtkBox or a #GtkGrid
* and include your widgets in it. Then, set the container as
* see gtk_file_chooser_add_filter(), but it is also possible
* to manually use a filter on a file with gtk_file_filter_filter().
*
- * ## GtkFileFilter as GtkBuildable
+ * # GtkFileFilter as GtkBuildable
*
* The GtkFileFilter implementation of the GtkBuildable interface
* supports adding rules using the <mime-types>, <patterns>
* The #GtkFontChooserDialog widget is a dialog for selecting a font.
* It implements the #GtkFontChooser interface.
*
- * ## GtkFontChooserDialog as GtkBuildable
+ * # GtkFontChooserDialog as GtkBuildable
*
* The GtkFontChooserDialog implementation of the #GtkBuildable
* interface exposes the buttons with the names "select_button"
* top side of the frame. The position of the
* label can be controlled with gtk_frame_set_label_align().
*
- * ## GtkFrame as GtkBuildable
+ * # GtkFrame as GtkBuildable
*
* The GtkFrame implementation of the GtkBuildable interface
* supports placing a child in the label position by specifying
* gtk_widget_show (info_bar);
* ]|
*
- * ## GtkInfoBar as GtkBuildable
+ * # GtkInfoBar as GtkBuildable
*
* The GtkInfoBar implementation of the GtkBuildable interface exposes
* the content area and action area as internal children with the names
* implies, most labels are used to label another widget such as a
* #GtkButton, a #GtkMenuItem, or a #GtkComboBox.
*
- * ## GtkLabel as GtkBuildable
+ * # GtkLabel as GtkBuildable
*
* The GtkLabel implementation of the GtkBuildable interface supports a
* custom <attributes> element, which supports any number of <attribute>
* sense with translatable attributes. Use markup embedded in the translatable
* content instead.
*
- * ## Mnemonics
+ * # Mnemonics
*
* Labels may contain “mnemonics”. Mnemonics are
* underlined characters in the label, used for keyboard navigation.
* gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry);
* ]|
*
- * ## Markup (styled text)
+ * # Markup (styled text)
*
* To make it easy to format text in a label (changing colors,
* fonts, etc.), label text can be provided in a simple <link
* end_index for a #PangoAttribute requires knowledge of the exact string
* being displayed, so translations will cause problems.
*
- * ## Selectable labels
+ * # Selectable labels
*
* Labels can be made selectable with gtk_label_set_selectable().
* Selectable labels allow the user to copy the label contents to
* the clipboard. Only labels that contain useful-to-copy information
* — such as error messages — should be made selectable.
*
- * ## Text layout
+ * # Text layout
*
* A label can contain any number of paragraphs, but will have
* performance problems if it contains more than a small number.
* #GtkLabel:max-width-chars has changed a bit with the introduction of
* <link linkend="geometry-management">width-for-height geometry management.</link>
*
- * ## Links
+ * # Links
*
* Since 2.18, GTK+ supports markup for clickable hyperlinks in addition
* to regular Pango markup. The markup for links is borrowed from HTML, using the
* }
* ]|
*
- * ## Performance Considerations
+ * # Performance Considerations
*
* Internally, the #GtkListStore was implemented with a linked list with
* a tail pointer prior to GTK+ 2.6. As a result, it was fast at data
* access to a particular row is needed often and your code is expected to
* run on older versions of GTK+, it is worth keeping the iter around.
*
- * ## Atomic Operations
+ * # Atomic Operations
*
* It is important to note that only the methods
* gtk_list_store_insert_with_values() and gtk_list_store_insert_with_valuesv()
* #GtkTreeModelFilterVisibleFunc to be visited with an empty row first; the
* function must be prepared for that.
*
- * ## GtkListStore as GtkBuildable
+ * # GtkListStore as GtkBuildable
*
* The GtkListStore implementation of the GtkBuildable interface allows
* to specify the model columns with a <columns> element that may
* gtk_accel_label_set_accel (GTK_ACCEL_LABEL (child), GDK_KEY_1, 0);
* ]|
*
- * ## GtkMenuItem as GtkBuildable
+ * # GtkMenuItem as GtkBuildable
*
* The GtkMenuItem implementation of the #GtkBuildable interface
* supports adding a submenu by specifying "submenu" as the "type"
* user to perform application functions. A #GtkMenuItem can have a
* submenu associated with it, allowing for nested hierarchical menus.
*
- * ## Terminology
+ * # Terminology
*
* A menu item can be "selected", this means that it is displayed
* in the prelight state, and if it has a submenu, that submenu
* Use gtk_menu_tool_button_new() to create a new
* #GtkMenuToolButton.
*
- * ## GtkMenuToolButton as GtkBuildable
+ * # GtkMenuToolButton as GtkBuildable
*
* The GtkMenuToolButton implementation of the GtkBuildable interface
* supports adding a menu by specifying "menu" as the "type"
* dialog);
* ]|
*
- * ## GtkMessageDialog as GtkBuildable
+ * # GtkMessageDialog as GtkBuildable
*
* The GtkMessageDialog implementation of the GtkBuildable interface exposes
* the message area as an internal child with the name "message_area".
* will be a popup menu allowing the users to switch pages.
* (see gtk_notebook_popup_enable(), gtk_notebook_popup_disable())
*
- * ## GtkNotebook as GtkBuildable
+ * # GtkNotebook as GtkBuildable
*
* The GtkNotebook implementation of the #GtkBuildable interface
* supports placing children into tabs by specifying "tab" as the
* More complicated placement of overlays is possible by connecting
* to the #GtkOverlay::get-child-position signal.
*
- * ## GtkOverlay as GtkBuildable
+ * # GtkOverlay as GtkBuildable
*
* The GtkOverlay implementation of the GtkBuildable interface
* supports placing a child as an overlay by specifying "overlay" as
* #GtkPrintOperation::draw-page, which you are supposed to catch
* and render the page on the provided #GtkPrintContext using Cairo.
*
- * ## The high-level printing API
+ * # The high-level printing API
*
* |[<!-- language="C" -->
* static GtkPrintSettings *settings = NULL;
*
* Printing support was added in GTK+ 2.10.
*
- * ## GtkPrintUnixDialog as GtkBuildable
+ * # GtkPrintUnixDialog as GtkBuildable
*
* The GtkPrintUnixDialog implementation of the GtkBuildable interface exposes its
* @notebook internal children with the name "notebook".
* applications that want to show an undeterminate value on the scale, without
* changing the layout of the application (such as movie or music players).
*
- * ## GtkScale as GtkBuildable
+ * # GtkScale as GtkBuildable
*
* GtkScale supports a custom <marks> element, which
* can contain multiple <mark> elements. The "value" and "position"
* by way of #GtkLabel:width-chars for instance. Widgets with static sizes as well
* as widgets that grow (such as ellipsizing text) need no such considerations.
*
- * ## GtkSizeGroup as GtkBuildable
+ * # GtkSizeGroup as GtkBuildable
*
* Size groups can be specified in a UI definition by placing an
* <object> element with `class="GtkSizeGroup"`
* </tgroup>
* </informaltable>
*
- * ## Custom styling in UI libraries and applications
+ * # Custom styling in UI libraries and applications
*
* If you are developing a library with custom #GtkWidget<!-- -->s that
* render differently than standard components, you may need to add a
* conceptual overview</link> which gives an overview of all the objects and
* data types related to the text widget and how they work together.
*
- * ## GtkTextTagTables as GtkBuildable
+ * # GtkTextTagTables as GtkBuildable
*
* The GtkTextTagTable implementation of the GtkBuildable interface
* supports adding tags by specifying "tag" as the "type"
* <link linkend="gtk3-GtkTreeView-drag-and-drop">drag and drop</link>
* interfaces.
*
- * ## GtkTreeStore as GtkBuildable
+ * # GtkTreeStore as GtkBuildable
*
* The GtkTreeStore implementation of the #GtkBuildable interface allows
* to specify the model columns with a <columns> element that may
* (and vice versa), for the latter gtk_tree_view_convert_bin_window_to_tree_coords()
* (and vice versa).
*
- * ## GtkTreeView as GtkBuildable
+ * # GtkTreeView as GtkBuildable
*
* The GtkTreeView implementation of the GtkBuildable interface accepts
* #GtkTreeViewColumn objects as <child> elements and exposes the
* If this has a value other than -1 you need to align the widget such that the baseline
* appears at the position.
*
- * ## Style Properties
+ * # Style Properties
*
* #GtkWidget introduces “style
* properties” - these are basically object properties that are stored
* style properties and gtk_widget_style_get_property(), gtk_widget_style_get() or
* gtk_widget_style_get_valist() to obtain the value of a style property.
*
- * ## GtkWidget as GtkBuildable
+ * # GtkWidget as GtkBuildable
*
* The GtkWidget implementation of the GtkBuildable interface supports a
* custom <accelerator> element, which has attributes named key,
* </object>
* ]|
*
- * ## Building composite widgets from template XML
+ * # Building composite widgets from template XML
*
* GtkWidget exposes some facilities to automate the proceedure
* of creating composite widgets using #GtkBuilder interface description
* control whether a window has a resize grip, use
* gtk_window_set_has_resize_grip().
*
- * ## GtkWindow as GtkBuildable
+ * # GtkWindow as GtkBuildable
*
* The GtkWindow implementation of the GtkBuildable interface supports a
* custom `<accel-groups>` element, which supports
projects / gtk4.git / commitdiff